home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Bavarian / Bavarian #108 (19xx)(APS Electronic).zip / Bavarian #108 (19xx)(APS Electronic).adf / PowerPackerEnglish < prev    next >
Text File  |  1988-08-03  |  34KB  |  782 lines
  1.  
  2.  
  3.  
  4.                         Power Packer 2.3a User Manual
  5.  
  6.                                 Aug 14, 1989
  7.  
  8.  
  9.  
  10. Preface
  11. =======
  12.  
  13.      Congratulations, you have just obtained a copy of PowerPacker 2.3a,
  14. PowerPeak's command and data cruncher for the Amiga.  If you have suggestions
  15. or remarks about this program, or if you find any bugs, please let me know.
  16.      This version of PowerPacker is shareware, this means that if you use it
  17. a lot I would appreciate it if you'd send me a contribution of $10 US or the
  18. same amount in any other currency.  This money will enable me to produce more
  19. programs on the Amiga.  If you send $15 US ($20 US overseas) I will send you
  20. the latest version of PowerPacker.  Please send money by international money
  21. order, EuroCheck (in Belgian Francs (BF) !!!!!) or cash, it's difficult for
  22. me to cash in other checks.  If you send for an update please state your
  23. current version, if there is no higher version at the time I get your letter
  24. I won't reply until I finish the next version, so don't be alarmed if it
  25. takes a while !
  26.      If  you want to use PowerPacker for commercial purposes you need written
  27. permission.
  28.  
  29.      Write to the following address:
  30.  
  31.                                 Nico François
  32.                                 Corbielaan 13
  33.                              3060 Bertem BELGIUM
  34.  
  35.  
  36. Contents
  37. ========
  38.  
  39. 1. The Packer
  40.      1.1 An introduction
  41.      1.2 The file requester
  42.      1.3 The basic menus
  43.           1.3.1 Project
  44.           1.3.2 Prefs
  45.           1.3.3 Crypt
  46.  
  47. 2. Recrunch
  48.      2.1 How ?
  49.      2.2 Why ?
  50.  
  51. 3. The HunkLab
  52.      3.1 Preferences
  53.      3.2 Process file
  54.  
  55. 4. The Script Menu
  56.  
  57. 5. The Supervisor Window
  58.  
  59. 6. A Sample Session
  60.  
  61. 7. PowerPacker 2.3a & the CLI
  62.  
  63. 8. PowerPacker 2.3a & other programs
  64.      8.1 Introduction
  65.      8.2 The function
  66.      8.3 Loading encrypted files
  67.      8.4 Compiling and linking
  68.      8.4 An example
  69.  
  70.  
  71. 1. The Packer
  72. -------------
  73.  
  74. 1.1 An introduction
  75.  
  76.      PowerPacker is a userfriendly command and data cruncher, this means a
  77. menu driven utility that can crunch almost any file on your disks.  It can be
  78. started from the CLI or the WorkBench, just type it's name in the CLI window
  79. or doubleclick it's icon.  PowerPacker will detach itself from the CLI so you
  80. can close the CLI window.  When you use it for the first time it's best to
  81. maintain a certain order in your actions (as we will see in chapter 6 of this
  82. document):
  83.  
  84.   (a) Check the packer options at the beginning of a session (Prefs menu)
  85.   (b) Load the file from disk (Project menu)
  86.   (c) Wait for the file to (de)crunch.
  87.   (d) Save the file back to disk (Project menu)
  88.  
  89.      Apart from crunching, you can also recrunch files that were crunched by
  90. most other crunchers.
  91.      The HunkLab enables you to e.g. force code or data in chip ram.
  92.      The script allows you to e.g. crunch a dozen of files overnight.
  93.  
  94.      Before I demonstrate how to use PowerPacker, let's look at the file
  95. requester and a brief overview of the menus and capabilities.
  96.  
  97.  
  98. 1.2 The file requester
  99.  
  100.     Whenever you are required to enter a filename, the packer sets up a file
  101. requester.  This requester automatically contains all devices connected to
  102. your Amiga and lists all the files (and their length) of a selected
  103. directory.  You don't have to wait for the directory read to end.  You can
  104. select a file or directory the moment you see it, or you can enter it in the
  105. appropriate string gadget.
  106.     However, if you wait for the directory read to end and quit the file
  107. requester, the next time you use it all the files will still be there, so you
  108. don't have to wait for the directory to be read again (This is very useful
  109. when you are recording a script, as you'll see later).  This feature has one
  110. disadvantage :  if files are changed or added to the selected directory they
  111. won't be shown in the list, or they will be shown with the wrong filelength,
  112. the next time the requester appears.  Therefore, if you think anything has
  113. been changed to the selected directory, use the 'GET DIR' gadget to re-read
  114. the directory.  (E.g.  when you save a crunched file on top of the old one,
  115. the old file length will be shown in the requester.)
  116.      When the 'Sort Files' switch in the prefs menu is checked the files will
  117. be alphabetically sorted in the requester.  This switch is present because
  118. some people don't like the files being sorted and jumping up and down the
  119. requester, they think it's annoying to try and catch the file you want. (and
  120. they are right of course :-)
  121.  
  122.  
  123. 1.3 The basic menus
  124.  
  125. 1.3.1 Project
  126.  
  127.     The project menu contains the file manipulation options.  Most of them
  128. speak for themselves:
  129.  
  130.   Load      ->  Load a file from disk and start the (de)crunching.
  131.   Save      ->  Save the (de)crunched or processed file in memory to disk.
  132.   Delete    ->  Delete a file from disk.
  133.   WorkBench ->  Open or close WorkBench if possible. (Adds 42K !)
  134.   Sleep     ->  Put PowerPacker to sleep on the WorkBench Screen, this
  135.                 frees 40-50K.
  136.                 WARNING: All buffers will be deallocated, so you are advised
  137.                          to save things first.
  138.   About...  ->  Show general information and my address.
  139.   Quit      ->  Quit the program.
  140.  
  141. 1.3.2 Prefs
  142.  
  143.      The prefs menu contains all the (de)cruncher settings.  You can select
  144. to (de)crunch command files or a data files.  If you want the crunched
  145. version of your file to be executable, select 'Command file'.  Now
  146. PowerPacker knows it has to add a decrunch header (572 bytes).  If the file
  147. you want to crunch only contains data (e.g. source codes of your programs),
  148. select the 'Data file' option.  This can be handy if you're going to use the
  149. PowerPacker CLI commands.  I'll discuss these commands in chapter 7 of this
  150. document.  Finally you have to choose whether you want to crunch or decrunch
  151. the load file.
  152.  
  153. NOTE: - PowerPacker will automatically decrunch a previously crunched
  154.         file.  You don't have to select crunch or decrunch mode anymore as
  155.         in PowerPacker 2.0a.
  156.  
  157.      The 'Decrunch Color' submenu contains the following options :
  158.  
  159.   Color 0   ->  The background color will change while decrunching
  160.   Color 1   ->  The text color changes
  161.   Pointer   ->  Only the mousepointer's color changes
  162.   Scroll    ->  Handy for decrunching a demo (just try it out !)
  163.   None      ->  If your eyes are wearing out.
  164.  
  165.      These options indicate what color will flash when a file is decrunched.
  166. You can change this option before saving a crunched file, so you can save a
  167. version of your crunched program that flashes in color 1, and one that
  168. flashes in the mouse pointer.  The default value is 'Pointer'.
  169.  
  170.      In the efficiency submenu you will find the following possibilities :
  171.  
  172.   Fast      ->  Use for small files, or for quick crunch.
  173.   Mediocre  ->  Better but slower.
  174.   Good      ->  Default, gains 40-50% in most cases.
  175.   Very Good ->  Also very slow !
  176.   Best      ->  Advised for script use only, ultra slow !!!
  177.  
  178. NOTE: - 'Fast' is approx. 4 times faster than 'Good', 'Very Good' is
  179.         2 times slower and 'Best' 4 times.
  180.       - 'Best' isn't always the best.  Small files crunch best with
  181.         'Very Good' or even 'Good'.
  182.  
  183.      The remaining preference switches:
  184.  
  185.   Data suffix  -> Attach '.pp' suffix to data files after crunching or remove
  186.                   '.pp' after decrunching.  It is advised that you leave this
  187.                   switch on so you can easily spot crunched data files.
  188.   Encrypt Data -> See section 1.3.3 of this manual.
  189.   Color Crunch -> Flash the selected decrunch color when crunching, giving
  190.                   you an idea what the decrunching will look like (provided
  191.                   that you don't change any options just before saving to
  192.                   disk).
  193.   LED Crunch   -> Your power-LED flashes while crunching, just like the
  194.                   screencolors. Now, you can even turn off your monitor and
  195.                   still see when the cruncher has finished.
  196.   Multitask    -> Switch multitasking off to (sligtly) increase the crunching
  197.                   speed.
  198.   Paging       -> Pause and wait for mouse button when supervisor window
  199.                   fills up.
  200.   Overwrite    -> Don't prompt if it's ok to overwrite a file when saving.
  201.   Sort files   -> Sort files in file requester.
  202.  
  203.      Use 'Save prefs' to save the preferences to your boot disk.  The
  204. preferences will be saved in the file 's:PowerPacker.prefs', this file will
  205. be enormous, euh, 6 bytes big.  When PowerPacker 2.3a is first started it
  206. will attempt to load this file and adjust the preferences.
  207.  
  208. NOTE: - While crunching, you can press both mousebuttons at the same
  209.         time to abort.
  210.       - Do *NOT* change disks when you are crunching with the multitasking
  211.         switched off !!!  The Amiga will crash !!!
  212.  
  213. 1.3.3 Crypt
  214.  
  215.      When the 'Encrypt Data' switch is on PowerPacker will not only crunch
  216. data files, it will also encrypt them so nobody else but you can decrunch
  217. them.  Just before crunching a data file PowerPacker will ask you for a
  218. password.  You will be presented with a string gadget with a special feature,
  219. it won't show you what you are typing !  After entering your password you
  220. will be asked to enter it again, this is done to verify that you haven't made
  221. a typing error (unless you make the same error twice :-).
  222.      You can also use the 'Last' gadget to re-enter your last password again,
  223. or the 'Abort' gadget to abort the encryption and just crunch the file.
  224.      When you try to load a crunched encrypted data file PowerPacker will
  225. once again prompt you for your password.  If you enter the correct one the
  226. data file will be decrypted and decrunched.  If you don't know the password,
  227. bad luck, there is no way you can decrunch this file !!
  228.  
  229. NOTE: - Encryption can currently not be used in a script.
  230.       - Your password can be up to 16 characters long, any character is
  231.         accepted, lowercase and uppercase are DIFFERENT !!!!
  232.       - Take care when using the 'Last' gadget, be sure to know what your
  233.         last password was.
  234.       - Don't forget your password !!  It is *IMPOSSIBLE* to decrypt a file
  235.         without the password !!!!!
  236.  
  237.  
  238. 2. Recrunch
  239. -----------
  240.  
  241. 2.1 How ?
  242.  
  243.      This menu is provided for the people who were using another cruncher or
  244. an older version of PowerPacker.  Just select 'Recrunch File' or 'Decrunch
  245. Only' and load the file.  PowerPacker will start the correct decrunch
  246. algorithm.  If you selected 'Recrunch' PowerPacker will start to crunch the
  247. decrunched file.  If PowerPacker doesn't recognize the cruncher it will say
  248. so, no harm is done.  If you select 'Recrunch Always' PowerPacker will always
  249. recrunch, even if the file was crunched with this version of PowerPacker.
  250. Useful for recrunching files using a higher efficiency.  (e.g. recrunch a
  251. 'Fast' crunched file with 'Best')
  252.  
  253.      Crunchers currently supported are:  'ANC Cruncher', 'TNM Cruncher 1.1',
  254. 'Relokit 1.0', 'HQC Cruncher 2.0', 'MasterCruncher 3.0', 'DragPack 1.0' and
  255. older PowerPacker files.  If you'd like to see other crunchers supported,
  256. send me the cruncher and some programs crunched with it.  (Together with a
  257. contribution I hope).  If it is possible to develop a decrunch algorithm I
  258. will include it in the next version of PowerPacker.
  259.  
  260. 2.2 Why ?
  261.  
  262.      PowerPacker always crunches better than the 'ANC Cruncher', 'TNM
  263. Cruncher' and 'HQC Cruncher'.  It crunches better than 'Relokit' most of the
  264. time, but even if it doesn't, I advise you to recrunch because 'Relokit' has
  265. some serious disadvantages (e.g. while the decrunched file is running, the
  266. crunched version still eats memory).  In contrast PowerPacker only eats about
  267. 530 bytes while your file is running, and (of course) frees it afterwards.
  268.  
  269. NOTE: - If you want to recrunch a PowerPacker 1.1 or 2.0 crunched file,
  270.         PowerPacker just replaces the file header with the improved and
  271.         debugged 2.1+ header. (Unless you've selected 'Recrunch Always')
  272.       - The recrunch menu only supports command files !  You can't recrunch
  273.         data files from e.g. PowerPacker 1.1, sorry.
  274.       - 'Decrunch Only' is not 100% guaranteed for 'Relokit 1.0' files,
  275.         'Recrunch' however is 100% ok ! (It's a strange world ! :-)
  276.       - Several people sent me 'dirty' crunchers, these are crunchers that
  277.         use absolute addresses (an absolute TABOO !!!).  It is impossible
  278.         to develop a decrunch algorithm for these.  (In fact, nothing should
  279.         have been crunched with these crunchers in the first place !)
  280.  
  281.  
  282. 3. The Hunklab
  283. --------------
  284.  
  285. 3.1 Preferences
  286.  
  287.      This menu is not really part of the PowerPacker crunch/decrunch routines
  288. but it wasn't worth writing a separate program for and a HunkLab is after all
  289. a very interesting utility.  You can e.g. use it to remove symbol and debug
  290. hunks from files that wouldn't crunch otherwise.
  291.  
  292.      You can force a program's code, data or BSS (uninitialised data) into
  293. chip ram or you can remove symbol tables and debug information just by
  294. toggling the marker on/off.  So in future, when you want your programs to be
  295. able to run on a one megabyte system, a simple click on the mousebutton will
  296. do.
  297.  
  298. 3.2 Process file
  299.  
  300.      'Process file' reads the file from disk and changes it according to your
  301. preferences.  To save the processed file, use 'Save' from the Project menu.
  302.      'Process & Crunch' will process the file and crunch the file afterwards
  303. (if possible).  To save use 'Save' in the Project menu.
  304.  
  305. NOTE: - Debug and symbol hunks are only used in debuggers, so you can safely
  306.         remove them from a program. (Unless you want to debug the program.)
  307.  
  308.  
  309. 4. The Script Menu
  310. ------------------
  311.  
  312.      The script is something that will save you a lot of time, it allows you
  313. to record 80 different commands to be executed after each other.  It is ideal
  314. for crunching a lot of files overnight.  Menu options are:
  315.  
  316.      'Clear Script' and 'List Script':
  317.           will do just that.
  318.      'Script Log File':
  319.           is used to specify a file to redirect output to.  If you cancel
  320.           the requester no log file is used.
  321.      'Destination Dir':
  322.           is used to specify the directory to save to.  It is ghosted in
  323.           normal use.
  324.      'Start Recording':
  325.           is used to start the recording of the script. If the script was
  326.           empty you will be asked for the destination directory.
  327.               After selecting the destination you can start entering the
  328.           script commands.  Everything that is ghosted is not available as a
  329.           command.  Just enter everything as if you were actually using
  330.           PowerPacker.  When you e.g. choose 'Load' PowerPacker will ask a
  331.           list of files to be (de)crunched. Press 'CANCEL' to exit the
  332.           entry.
  333.           NOTE: - You can still change the source and destination dir while
  334.                   recording.
  335.           Every command you enter will be displayed in the supervisor window.
  336.      'Stop Recording':
  337.           is used to exit the recording mode.
  338.      'Delete Last':
  339.           will delete the last command after a confirmation.
  340.      'Execute Script':
  341.           will start the playback of the script commands.  If you press the
  342.           menu button a requester will appear to ask you if you want to abort
  343.           the script execution.
  344.               After executing the script a request to clear the script will
  345.           appear.
  346.  
  347. NOTE: - It is advisable to let the filerequester buffer fill before you
  348.         start selecting files.  It is also better not to change the source
  349.         directory too often.
  350.       - The screen turns grey to indicate a script is executing.
  351.       - While executing a script, PowerPacker will always act destructive !
  352.         Files will allways be overwritten and deleted !!!
  353.  
  354.  
  355. 5. The Supervisor Window
  356. ------------------------
  357.  
  358.      This window displays all kind of useful information like the file
  359. status, crunch messages, and error messages.  You can follow all steps, from
  360. the original file that is loaded into memory, to the final crunched version
  361. on disk.  When an executable file is loaded, its hunk information is
  362. displayed.  This information is rather technical, but it can be useful for
  363. programmers.  If you're not interested, just ignore it.
  364.  
  365.      I think it might be useful to give a list of possible error messages:
  366.  
  367. (De)crunch :  Buffer overflow !
  368.                 (Crunched file is getting longer than original file)
  369.               Crunch aborted !
  370.                 (Crunching stopped by user or by buffer overflow)
  371.               No memory for decrunch buffer !
  372.               Out of memory !
  373.                 (Buy some more, try selling your WorkBench :-)
  374.               Sorry, can't crunch !
  375.                 (This is a polite program)
  376.               Can't find hunk_header.
  377.               Hunk not allowed in load file!
  378.               Unknown Hunk !
  379.                 (Not a command file)
  380.               Hunk not supported (yet ?) !
  381.                 (If it's a symbol or debug hunk, try removing it in HunkLab)
  382.               Nothing to save !
  383.                 (Buffer is empty)
  384.               Save Aborted !
  385.               Error reading file !
  386.               Can't open file !
  387.               Error writing data header !
  388.               Error writing buffer !
  389.               File not found !
  390.               Couldn't delete file !
  391.               Can't open file !
  392.                 (Disk errors)
  393.  
  394. Recrunch :    No need to recrunch 'PowerPacker 1.1' command file,
  395.               Replacing 1.1 decrunch header with 2.3 header...
  396.                 (2.1+ header is shorter and bugfree, 1.1 isn't !!)
  397.               No need to recrunch 'PowerPacker 2.0' command file,
  398.               Replacing 2.0 decrunch header with 2.3 header...
  399.                 (There was still a small bug in 2.0 header, so replace it.)
  400.               Not crunched with one of the supported crunchers !!
  401.                 (Or file isn't crunched at all !)
  402.               Sorry, can't recrunch !
  403.                 (Please don't sue me :-)
  404.  
  405. Process :     Sorry, can't process file !
  406.                 (File is probably not a command file)
  407.               Can't crunch file !
  408.                 (File contains unsupported hunks)
  409.  
  410. Script :      Script buffer full !! Please stop recording.
  411.                 (Script is limited to 80 commands, select 'Stop Recording')
  412.  
  413.  
  414. 6. A Sample Session
  415. -------------------
  416.  
  417.      Now that I have explained PowerPacker's capabilities, it's time for
  418. a little demonstation.  Let's say we want to crunch the 'CLI' command in the
  419. System directory on your Workbench 1.2 disk.
  420.  
  421.      Select 'Pointer' in the Prefs/Decrunch Color menu (When I wrote this
  422. text, it was very late and I couldn't stand the other decrunch colors
  423. anymore !)
  424.  
  425.      Set 'Prefs' to 'Command file'.  Now select 'Load' in the Project menu
  426. (the file requester will appear), insert your WorkBench 1.2 disk and choose
  427. the 'CLI' command in the system directory.  Now you'll see a lot of hunk
  428. (or junk ?? :-) information about the CLI command:
  429.  
  430.                                                                              
  431.      Scanning file 'df0:System/CLI'...                                       
  432.      Loading command file...                                                 
  433.                                                                              
  434.      Hunk_header (0x03F3)                                                    
  435.         9 hunks (0 to 8).                                                    
  436.      Hunk  0 : Hunk_code (0x03E9)     (524 bytes)                            
  437.                Hunk_reloc32 (0x03EC)                                         
  438.      Hunk  1 : Hunk_data (0x03EA)     (428 bytes, 0 BSS)                     
  439.      Hunk  2 : Hunk_code (0x03E9)     (472 bytes)                            
  440.                Hunk_reloc32 (0x03EC)                                         
  441.      Hunk  3 : Hunk_data (0x03EA)     (52 bytes, 0 BSS)                      
  442.      Hunk  4 : Hunk_code (0x03E9)     (16 bytes)                             
  443.      Hunk  5 : Hunk_code (0x03E9)     (0 bytes)                              
  444.      Hunk  6 : Hunk_code (0x03E9)     (196 bytes)                            
  445.                Hunk_reloc32 (0x03EC)                                         
  446.      Hunk  7 : Hunk_code (0x03E9)     (68 bytes)                             
  447.                Hunk_reloc32 (0x03EC)                                         
  448.      Hunk  8 : Hunk_data (0x03EA)     (0 bytes, 0 BSS)                       
  449.                                                                              
  450.      Crunching command file...                                               
  451.      Press left and right button to abort.                                   
  452.      Crunching, please wait.                                                 
  453.                                                                              
  455.      The cruncher displays the percentage of the file already crunched and
  456. the gain so far. After some time your screen will look like this:
  457.  
  458.                                                                              
  459.      100% crunched.                                                          
  460.      Done.                                                                   
  461.      Original length : 2356 bytes.                                           
  462.      Crunched length : 1204 (1776) bytes.                                    
  463.      Gained 49% (1152 bytes) !                                               
  464.                                                                              
  466.      The only thing you have to do now is save this back to disk as an
  467. executable file.  Now enjoy the crunched CLI command.
  468.  
  469.  
  470. 7. PowerPacker 2.3a & the CLI
  471. -----------------------------
  472.  
  473.      For your convenience, I have also written two CLI commands, one to
  474. crunch and one to decrunch data files.
  475.      From version 2.3 onwards the CLI commands use the magnificent ARP
  476. library !!!  This means they have been greatly enhanced:  wildcards are fully
  477. supported, options can be entered in any order, directories will be created
  478. when needed, etc...  Make sure the arp.library is in your LIBS:  directory
  479. when you run these commands.
  480.      A usage line is given by typing 'Crunch' or 'Decrunch' without
  481. arguments.  You'll get something like this:
  482. _____________________________________________________________________________
  483.  
  484. 1> Crunch
  485. POWER-PACKER 2.3a Data Cruncher.
  486.   Written by Nico François (POWER PEAK)
  487. Usage : Crunch <source> <destination> [EFFICIENCY 1-5] [COLOR 0-4] [CRYPT]
  488.                                       [NOSUFF] [NOLED] [FORBID] [NOPER]
  489. With:
  490.   EFFICIENCY: 1 = Fast, 2 = Mediocre, 3 = Good (def), 4 = Very Good, 5 = Best
  491.   COLOR     : 0/1 = Color 0/1, 2 = Pointer (def), 3 = Scroll, 4 = None
  492.   CRYPT     : Encrypt file.
  493.   NOSUFFIX  : Don't attach '.pp' suffix to filename.
  494.   NOPER     : Don't print percentage.
  495.   NOLED     : Disable led crunch.
  496. Hit ^C to abort, ^D to abort crunching only.
  497.  
  498. 1> Decrunch
  499. POWER-PACKER 2.3a Data Decruncher.
  500.   Written by Nico François (POWER PEAK)
  501. Usage : Decrunch <source> <destination> [COLOR 0-4] [OPT B|F] [SKIP] [QUIET]
  502. With:
  503.    COLOR: 0/1 = Color 0/1, 2 = Pointer (def), 3 = Scroll, 4 = None
  504.    SKIP : Skip uncrunched files.
  505.    QUIET: Be quiet.
  506. If <destination> is '*' or is omited, files will be typed to Output().
  507. Options effective when typing:
  508.    OPT B will print a banner before and
  509.    OPT F will print a formfeed after each file.
  510. Hit ^C to abort, ^D to abort typing only.
  511.  
  512. 1>
  513. _____________________________________________________________________________
  514.  
  515.      These commands are useful to be included in your startup-sequence or to
  516. read crunched text files quickly.
  517.  
  518.   Some examples:
  519.  
  520.      Crunch df0:source/*.c TO ram:source COL 4 NOLED
  521.  
  522.      This will result in a crunching of every C program in the df0:source
  523. directory.  If the ram:source directory exists the files will be saved there,
  524. if it doesn't it will be created if there is more than one C program in
  525. df0:source.  The '.pp' suffix will be attached to the filenames.  The led
  526. will not flicker, no crunch color is used.
  527.  
  528.      Decrunch >PRT: QUIET dh0:progs/*.asm.pp OPT BF COL 3
  529.  
  530.      Every crunched assembler program will be decrunched and printed, before
  531. each file a banner will be printed, each file will start on a new page.  If
  532. the file is encrypted you will be prompted for a password.  It is very
  533. important that you use the QUIET option here, if you don't the copyright and
  534. information lines will also be printed.  The mouse pointer will flash while
  535. decrunching.
  536.  
  537. NOTE: - These commands only (de)crunch DATA files !!!!  (So to (de)crunch
  538.         executable files, you'll still have to use PowerPacker 2.3a).
  539.  
  540.  
  541. 8. PowerPacker 2.3a & other programs
  542. ------------------------------------
  543.  
  544. 8.1 Introduction
  545.  
  546.      This one is for the programmers among you !
  547.      From release 2.3 onwards the decrunch source is included.  I decided to
  548. do this so other programs could load data files crunched with PowerPacker.
  549. As an example I could refer to one of my other utilities : PPMore, this is a
  550. text viewing utility (like more, hence the name) that can also display ASCII
  551. files crunched with PowerPacker.
  552.      Source is presented as a support function 'PP_LoadData', this function
  553. will load a data file and will decrunch it if necessary.  When the file isn't
  554. crunched it'll just be loaded.  Encrypted files are also supported.
  555.      The source was written for Aztec C 3.6a.  If you want to compile it with
  556. Lattice you will have to seperate C and assembler, compile/assemble them
  557. separatly and link them together.  You can use this code for non-commercial
  558. programs as long as you leave my copyright notice intact.
  559.  
  560. 8.2 The function
  561. _____________________________________________________________________________
  562.  
  563.   error = PP_LoadData (file, color, typeofmem, buffptr, lengthptr, password);
  564.  
  565.   with:
  566.      char *file;         filename of file to be loaded
  567.      UBYTE color;        decrunch color (see ppdata.h)
  568.      ULONG typeofmem;    type of memory to be allocated
  569.      UBYTE **buffptr;    address of buffer pointer variable
  570.      ULONG *lengthptr;   address of length variable
  571.      char *password;     pointer to password string or NULL
  572.  
  573.   Note:
  574.      - error and color codes are defined in <ppdata.h>.
  575.      - memory must be freed by caller after usage : FreeMem (buff, length);
  576. _____________________________________________________________________________
  577.  
  578.      You have the following decrunch colors available:
  579.  
  580.           DECR_COL0      Decrunch in color 0
  581.           DECR_COL1         ''    '' color 1
  582.           DECR_POINTER      ''    '' the mouse pointer
  583.           DECR_SCROLL       ''    '' the scroll register
  584.           DECR_NONE      No decrunch color is used
  585.  
  586.      The following errors can occure:
  587.  
  588.           PP_LOADOK      No error, file loaded succesfully.
  589.           PP_LOCKERR     Couldn't lock file, file probably doesn't exist.
  590.           PP_OPENERR     Couldn't open file.
  591.           PP_READERR     Read error.
  592.           PP_NOMEMORY    No memory to allocate buffer for data file.
  593.           PP_CRYPTED     File is crypted and no password was provided.
  594.           PP_PASSERR     File is crypted and wrong password provided.
  595.  
  596. 8.3 Loading encrypted files
  597.  
  598.      To load encrypted files a password has to be provided to the function.
  599. First of all try to load the file with a NULL pointer for 'password', when
  600. you get the PP_CRYPTED error you know that the file is encrypted.  Then
  601. prompt the user for a password and call the function again with the same
  602. parameters, but now 'password' points to the password string.  If PP_LoadData
  603. returns PP_LOADOK the file was decrypted, if it returns PP_PASSERR the
  604. password was incorrect.  If it returns anything else some sort of error
  605. occured (see <ppdata.h> for the error codes).
  606.  
  607. 8.4 Compiling and linking
  608.  
  609.      - If you use Aztec C you have one module to compile : ppdata.c
  610.  
  611.      cc [options] ppdata.c
  612.  
  613.      Use the same options you use in the other modules of your program.
  614. Compile the other modules of your program and link everything together:
  615.  
  616.      ln +q main.o ... ppdata.o -lc -o myprog
  617.  
  618.      - If you use Lattice C you will have to seperate the C source from the
  619. assembler source and compile/assemble them seperatly.  You will then get two
  620. object files.  When you then link everything together be sure to link with
  621. both these object files.  (I haven't tried it, but it should work)
  622.  
  623. 8.5 An example
  624.  
  625.      This small (incomplete) program shows you how to use the support
  626. function in your programs.
  627.  
  628. /*********
  629. * test.c *
  630. *********/
  631.  
  632. #include <exec/types.h>
  633. ...
  634. #include <ppdata.h>
  635.  
  636. UBYTE *buffer = NULL;
  637. ULONG bufferlength;
  638. UBYTE password[17];
  639.  
  640. main()
  641. {
  642.      int error;
  643.  
  644.      error = PP_LoadData ("df0:doc/Packer.doc.pp", DECR_POINTER, MEMF_PUBLIC,
  645.           &buffer, &bufferlength, NULL);     /* Don't forget the '&' !!!!! */
  646.      if (error != PP_LOADOK) switch (error) {
  647.           case PP_LOCKERR:
  648.                puts ("file not found !!!");
  649.                FreeStuffAndExit();
  650.           case PP_LOADERR:
  651.                puts ("loading error !!!");
  652.                FreeStuffAndExit();
  653.           case PP_NOMEMORY:
  654.                puts ("out of memory !!!");
  655.                FreeStuffAndExit();
  656.           ...
  657.           case PP_CRYPTED:
  658.                /* prompt the user for a password (max 16 chars) */
  659.                ...
  660.                error = PP_LoadData ("df0:docs/Packer.doc.pp", DECR_POINTER,
  661.                     MEMF_PUBLIC, &buffer, &bufferlength, password);
  662.                if (error == PP_PASSERR) {
  663.                     puts ("incorrect password !!!");
  664.                     FreeStuffAndExit();
  665.                     }
  666.                else if (error != PP_LOADOK) {
  667.                     puts ("correct password, but couldn't load !!!");
  668.                     FreeStuffAndExit();
  669.                     }
  670.                break;
  671.           }
  672.      /* now do something with the data file loaded at addr 'buffer' and with
  673.         length 'bufferlength' */
  674.      ...
  675.      /* DO NOT FORGET TO FREE THE MEMORY !! */
  676.      FreeMem (buffer, bufferlength);
  677. }
  678.  
  679. FreeStuffAndExit()
  680. {
  681.      /* free all your resources */
  682.      ...
  683.      exit (0);
  684. }
  685.                                              Enjoy this program !!!
  686.  
  687.  
  688.                               PROGRAM HISTORY:
  689.  
  690. *****************************************************************************
  691. VERSION 1.0a
  692.  
  693.      First release.
  694.  
  695. *****************************************************************************
  696. VERSION 1.1a
  697.  
  698.      Fixed bugs.
  699.      Improved crunch algorithm by about 5%.
  700.      'Delete' and 'Multitask' added.
  701.      Better menu structure.
  702.      Improved the file requester.
  703.      Written CLI commands.
  704.  
  705. *****************************************************************************
  706. VERSION 2.0a
  707.  
  708.      Fixed some more bugs.
  709.      Added buffer and automatic device-list to the file requester.
  710.      Added 'LED Crunch', useful for turning the monitor off while crunching,
  711.      and 'Paging'.
  712.      New header, bug fixed. (1.1 didn't free mem when started from WorkBench)
  713.      Added the hunklab.
  714.      Improved CLI commands.
  715.  
  716. *****************************************************************************
  717. VERSION 2.1a
  718.  
  719.      Fixed last bug in header (2.0 crashed when you were out of memory, oops)
  720.      Added script feature, now possible to crunch files overnight.
  721.      Improved requesters.
  722.      Automatic crunch/decrunch.
  723.      Improved menu structure considerably.
  724.      Intelligent recrunch implemented.
  725.      Automatic crunch/decrunch.
  726.      Added 'Color Crunch' option.
  727.      New efficiency 'Best' added.
  728.  
  729. *****************************************************************************
  730. VERSION 2.1b
  731.  
  732.      Bug fixed in script abort.
  733.      Added ability to open a log file during script execution.
  734.      Now possible to recrunch PowerPacker files with a higher efficiency.
  735.      Recrunch detects unsupported crunchers a lot faster.
  736.      PowerPacker now automatically opens a PAL/NTSC screen.
  737.  
  738. *****************************************************************************
  739. VERSION 2.2a
  740.  
  741.      All known bugs (or better, undocumented features) fixed.
  742.      'Sleep' mode implemented, useful for multitasking freaks.
  743.      While crunching the gain percentage so far is displayed.
  744.      Recrunch now supports 'HQC Cruncher 2.0', 'MasterCruncher 3.0'
  745.        and 'Dragpack 1.0'.
  746.      New graphics in title.
  747.  
  748. *****************************************************************************
  749. VERSION 2.3a
  750.  
  751.      PowerPacker detaches itself from the CLI, so the CLI window can be
  752.        closed or used for other things.
  753.      CLI commands are greatly enhanced, they now use ARP.
  754.      New switch : 'Overwrite' to surpress 'OK to overwrite ?' request.
  755.      File requester now able to sort files, 'Sort files' switch.
  756.      By popular demand: encryption of data files is now possible using the
  757.        new 'Encrypt Data' switch. Encryption should be IMPOSSIBLE to crack !!
  758.      Also by popular demand: Now possible to save preferences to boot disk.
  759.      More memory efficient decrunch and recrunch of PowerPacker files.
  760.      Decrunch source included, so other programs could be written that
  761.        would load data files crunched with PowerPacker.
  762.      'Data Suffix' switch to improve adding/removing of '.pp' suffix.
  763.      Decrunch color default 'Pointer'.
  764.      Improved scanning of files when loading or recrunching.
  765.      Fixed small bug (version 2.2a lost 256 bytes every time it was run).
  766.      More info in about window.
  767.  
  768. *****************************************************************************
  769.  
  770. P.S. This text file crunches to 43% of it's original length. (Gains 57% !)
  771.  
  772. PowerPacker 2.3a written by Nico François (Yes, Nico is my first name :-)
  773. Special thanks go to - Luc Pauwels for the icons and writing the 2.0a manual,
  774.                      - Jorrit Tybergein for the extensive debugging.
  775.                      - everybody who mailed me suggestions or remarks.
  776.  
  777. (c) 1989 Nico François / Power Peak
  778.  
  779.                                    //
  780.                        Thanks to \X/ Amiga for being the best computer ever !
  781.  
  782.